home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / QuickTime / QuickTime 3 Interfaces & Libs / QTDevMac / CIncludes / QD3DView.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-21  |  14.6 KB  |  452 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DView.h
  3.  
  4.      Contains:    View types and routines                                            
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.5.4
  7.                  Release:    QuickTime 3.0
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __QD3DVIEW__
  19. #define __QD3DVIEW__
  20.  
  21. #ifndef __QD3D__
  22. #include <QD3D.h>
  23. #endif
  24.  
  25. #ifndef __QD3DSTYLE__
  26. #include <QD3DStyle.h>
  27. #endif
  28. #ifndef __QD3DSET__
  29. #include <QD3DSet.h>
  30. #endif
  31.  
  32.  
  33.  
  34. #if PRAGMA_ONCE
  35. #pragma once
  36. #endif
  37.  
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41.  
  42. #if PRAGMA_IMPORT
  43. #pragma import on
  44. #endif
  45.  
  46. #if PRAGMA_STRUCT_ALIGN
  47.     #pragma options align=power
  48. #elif PRAGMA_STRUCT_PACKPUSH
  49.     #pragma pack(push, 2)
  50. #elif PRAGMA_STRUCT_PACK
  51.     #pragma pack(2)
  52. #endif
  53.  
  54. #if PRAGMA_ENUM_ALWAYSINT
  55.     #pragma enumsalwaysint on
  56. #elif PRAGMA_ENUM_OPTIONS
  57.     #pragma option enum=int
  58. #elif PRAGMA_ENUM_PACK
  59.     #if __option(pack_enums)
  60.         #define PRAGMA_ENUM_PACK__QD3DVIEW__
  61.     #endif
  62.     #pragma options(!pack_enums)
  63. #endif
  64.  
  65. /******************************************************************************
  66.  **                                                                             **
  67.  **                        View Type Definitions                                 **
  68.  **                                                                             **
  69.  *****************************************************************************/
  70.  
  71. enum TQ3ViewStatus {
  72.     kQ3ViewStatusDone            = 0,
  73.     kQ3ViewStatusRetraverse        = 1,
  74.     kQ3ViewStatusError            = 2,
  75.     kQ3ViewStatusCancelled        = 3
  76. };
  77. typedef enum TQ3ViewStatus TQ3ViewStatus;
  78.  
  79.  
  80. /******************************************************************************
  81.  **                                                                             **
  82.  **                        Default Attribute Set                                 **
  83.  **                                                                             **
  84.  *****************************************************************************/
  85. #define kQ3ViewDefaultAmbientCoefficient    1.0
  86. #define kQ3ViewDefaultDiffuseColor            0.5, 0.5, 0.5
  87. #define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
  88. #define kQ3ViewDefaultSpecularControl        4.0
  89. #define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0
  90. #define kQ3ViewDefaultHighlightState        kQ3Off
  91. #define kQ3ViewDefaultHighlightColor        1.0, 0.0, 0.0
  92. #define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodConstant
  93. #define kQ3ViewDefaultSubdivisionC1            10.0
  94. #define kQ3ViewDefaultSubdivisionC2            10.0
  95.  
  96. /******************************************************************************
  97.  **                                                                             **
  98.  **                            View Routines                                     **
  99.  **                                                                             **
  100.  *****************************************************************************/
  101. EXTERN_API_C( TQ3ViewObject )
  102. Q3View_New                        (void);
  103.  
  104. EXTERN_API_C( TQ3Status )
  105. Q3View_Cancel                    (TQ3ViewObject             view);
  106.  
  107. /******************************************************************************
  108.  **                                                                             **
  109.  **                        View Rendering routines                                 **
  110.  **                                                                             **
  111.  *****************************************************************************/
  112. EXTERN_API_C( TQ3Status )
  113. Q3View_SetRendererByType        (TQ3ViewObject             view,
  114.                                  TQ3ObjectType             theType);
  115.  
  116. EXTERN_API_C( TQ3Status )
  117. Q3View_SetRenderer                (TQ3ViewObject             view,
  118.                                  TQ3RendererObject         renderer);
  119.  
  120. EXTERN_API_C( TQ3Status )
  121. Q3View_GetRenderer                (TQ3ViewObject             view,
  122.                                  TQ3RendererObject *    renderer);
  123.  
  124. EXTERN_API_C( TQ3Status )
  125. Q3View_StartRendering            (TQ3ViewObject             view);
  126.  
  127. EXTERN_API_C( TQ3ViewStatus )
  128. Q3View_EndRendering                (TQ3ViewObject             view);
  129.  
  130. EXTERN_API_C( TQ3Status )
  131. Q3View_Flush                    (TQ3ViewObject             view);
  132.  
  133. EXTERN_API_C( TQ3Status )
  134. Q3View_Sync                        (TQ3ViewObject             view);
  135.  
  136.  
  137. /******************************************************************************
  138.  **                                                                             **
  139.  **                        View/Bounds/Pick routines                             **
  140.  **                                                                             **
  141.  *****************************************************************************/
  142. EXTERN_API_C( TQ3Status )
  143. Q3View_StartBoundingBox            (TQ3ViewObject             view,
  144.                                  TQ3ComputeBounds         computeBounds);
  145.  
  146. EXTERN_API_C( TQ3ViewStatus )
  147. Q3View_EndBoundingBox            (TQ3ViewObject             view,
  148.                                  TQ3BoundingBox *        result);
  149.  
  150. EXTERN_API_C( TQ3Status )
  151. Q3View_StartBoundingSphere        (TQ3ViewObject             view,
  152.                                  TQ3ComputeBounds         computeBounds);
  153.  
  154. EXTERN_API_C( TQ3ViewStatus )
  155. Q3View_EndBoundingSphere        (TQ3ViewObject             view,
  156.                                  TQ3BoundingSphere *    result);
  157.  
  158. EXTERN_API_C( TQ3Status )
  159. Q3View_StartPicking                (TQ3ViewObject             view,
  160.                                  TQ3PickObject             pick);
  161.  
  162. EXTERN_API_C( TQ3ViewStatus )
  163. Q3View_EndPicking                (TQ3ViewObject             view);
  164.  
  165.  
  166. /******************************************************************************
  167.  **                                                                             **
  168.  **                            View/Camera routines                             **
  169.  **                                                                             **
  170.  *****************************************************************************/
  171. EXTERN_API_C( TQ3Status )
  172. Q3View_GetCamera                (TQ3ViewObject             view,
  173.                                  TQ3CameraObject *        camera);
  174.  
  175. EXTERN_API_C( TQ3Status )
  176. Q3View_SetCamera                (TQ3ViewObject             view,
  177.                                  TQ3CameraObject         camera);
  178.  
  179.  
  180. /******************************************************************************
  181.  **                                                                             **
  182.  **                            View/Lights routines                             **
  183.  **                                                                             **
  184.  *****************************************************************************/
  185. EXTERN_API_C( TQ3Status )
  186. Q3View_SetLightGroup            (TQ3ViewObject             view,
  187.                                  TQ3GroupObject         lightGroup);
  188.  
  189. EXTERN_API_C( TQ3Status )
  190. Q3View_GetLightGroup            (TQ3ViewObject             view,
  191.                                  TQ3GroupObject *        lightGroup);
  192.  
  193.  
  194. /******************************************************************************
  195.  **                                                                             **
  196.  **                                Idle Method                                     **
  197.  **                                                                             **
  198.  *****************************************************************************/
  199. /*
  200.  *    The idle methods allow the application to register callback routines 
  201.  *    which will be called by the view during especially long operations.
  202.  *
  203.  *    The idle methods may also be used to interrupt long renderings or
  204.  *    traversals.  Inside    the idler callback the application can check for
  205.  *    Command-Period, Control-C or clicking a "Cancel" button or whatever else
  206.  *    may be used to let the user interrupt rendering.    
  207.  *
  208.  *    It is NOT LEGAL to call QD3D routines inside an idler callback.
  209.  *
  210.  *    Return kQ3Failure to cancel rendering, kQ3Success to continue. Don't
  211.  *    bother posting an error.
  212.  *
  213.  *    Q3View_SetIdleMethod registers a callback that can be called
  214.  *    by the system during rendering.  Unfortunately there is no way yet
  215.  *    to set timer intervals when you want to be called.  Basically, it is
  216.  *    up to the application's idler callback to check clocks to see if you
  217.  *    were called back only a millisecond ago or an hour ago!
  218.  *
  219.  *    Q3View_SetIdleProgressMethod registers a callback that also gives
  220.  *    progress information. This information is supplied by the renderer, and
  221.  *    may or may not be based on real time.
  222.  *
  223.  *    If a renderer doesn't support the progress method, your method will be
  224.  *    called with current == 0 and completed == 0.
  225.  *    
  226.  *    Otherwise, you are GUARANTEED to get called at least 2 or more times:
  227.  *    
  228.  *    ONCE            idleMethod(view, 0, n)        -> Initialize, Show Dialog
  229.  *    zero or more    idleMethod(view, 1..n-1, n) -> Update progress
  230.  *    ONCE            idleMethod(view, n, n)        -> Exit, Hide Dialog
  231.  *    
  232.  *    "current" is guaranteed to be less than or equal to "completed"
  233.  *    "completed" may change values, but current/complete always indicates
  234.  *    the degree of completion.
  235.  *
  236.  *    The calling conventions aid in managing any data associated with a 
  237.  *    progress user interface indicator.
  238.  */
  239. typedef CALLBACK_API_C( TQ3Status , TQ3ViewIdleMethod )(TQ3ViewObject view, const void *idlerData);
  240. typedef CALLBACK_API_C( TQ3Status , TQ3ViewIdleProgressMethod )(TQ3ViewObject view, const void *idlerData, unsigned long current, unsigned long completed);
  241. EXTERN_API_C( TQ3Status )
  242. Q3View_SetIdleMethod            (TQ3ViewObject             view,
  243.                                  TQ3ViewIdleMethod         idleMethod,
  244.                                  const void *            idleData);
  245.  
  246. EXTERN_API_C( TQ3Status )
  247. Q3View_SetIdleProgressMethod    (TQ3ViewObject             view,
  248.                                  TQ3ViewIdleProgressMethod  idleMethod,
  249.                                  const void *            idleData);
  250.  
  251.  
  252. /******************************************************************************
  253.  **                                                                             **
  254.  **                                EndFrame Method                                 **
  255.  **                                                                             **
  256.  *****************************************************************************/
  257. /*
  258.  *    The end frame method is an alternate way of determining when an
  259.  *    asynchronous renderer has completed rendering a frame. It differs from
  260.  *    Q3View_Sync in that notification of the frame completion is the opposite
  261.  *    direction. 
  262.  *    
  263.  *    With Q3View_Sync the application asks a renderer to finish rendering
  264.  *    a frame, and blocks until the frame is complete.
  265.  *    
  266.  *    With the EndFrame method, the renderer tells the application that is has
  267.  *    completed a frame.
  268.  *
  269.  *    If "Q3View_Sync" is called BEFORE this method has been called, this
  270.  *    method will NOT be called ever.
  271.  *    
  272.  *    If "Q3View_Sync" is called AFTER this method has been called, the
  273.  *    call will return immediately (as the frame has already been completed).
  274.  */
  275. typedef CALLBACK_API_C( void , TQ3ViewEndFrameMethod )(TQ3ViewObject view, void *endFrameData);
  276. EXTERN_API_C( TQ3Status )
  277. Q3View_SetEndFrameMethod        (TQ3ViewObject             view,
  278.                                  TQ3ViewEndFrameMethod     endFrame,
  279.                                  void *                    endFrameData);
  280.  
  281.  
  282. /******************************************************************************
  283.  **                                                                             **
  284.  **                            Push/Pop routines                                 **
  285.  **                                                                             **
  286.  *****************************************************************************/
  287. EXTERN_API_C( TQ3Status )
  288. Q3Push_Submit                    (TQ3ViewObject             view);
  289.  
  290. EXTERN_API_C( TQ3Status )
  291. Q3Pop_Submit                    (TQ3ViewObject             view);
  292.  
  293.  
  294. /******************************************************************************
  295.  **                                                                             **
  296.  **        Check if bounding box is visible in the viewing frustum.  Transforms **
  297.  **        the bbox by the current local_to_world transformation matrix and     **
  298.  **        does a clip test to see if it lies in the viewing frustum.             **
  299.  **        This can be used by applications to cull out large chunks of scenes     **
  300.  **        that are not going to be visible.                                     **
  301.  **                                                                             **
  302.  **        The default implementation is to always return kQ3True.  Renderers     **
  303.  **        may override this routine however to do the checking.                 **
  304.  **                                                                             **
  305.  *****************************************************************************/
  306. EXTERN_API_C( TQ3Boolean )
  307. Q3View_IsBoundingBoxVisible        (TQ3ViewObject             view,
  308.                                  const TQ3BoundingBox *    bbox);
  309.  
  310.  
  311. /******************************************************************************
  312.  **                                                                             **
  313.  **                            DrawContext routines                             **
  314.  **                                                                             **
  315.  *****************************************************************************/
  316. EXTERN_API_C( TQ3Status )
  317. Q3View_SetDrawContext            (TQ3ViewObject             view,
  318.                                  TQ3DrawContextObject     drawContext);
  319.  
  320. EXTERN_API_C( TQ3Status )
  321. Q3View_GetDrawContext            (TQ3ViewObject             view,
  322.                                  TQ3DrawContextObject *    drawContext);
  323.  
  324.  
  325. /******************************************************************************
  326.  **                                                                             **
  327.  **                            Graphics State routines                             **
  328.  **                                                                             **
  329.  ** The graphics state routines can only be called while rendering (ie. in     **
  330.  ** between calls to start and end rendering calls).  If they are called     **
  331.  ** outside of a rendering loop, they will return with error.                 **
  332.  **                                                                             **
  333.  *****************************************************************************/
  334. /******************************************************************************
  335.  **                                                                             **
  336.  **                            Transform routines                                 **
  337.  **                                                                             **
  338.  *****************************************************************************/
  339. EXTERN_API_C( TQ3Status )
  340. Q3View_GetLocalToWorldMatrixState (TQ3ViewObject         view,
  341.                                  TQ3Matrix4x4 *            matrix);
  342.  
  343. EXTERN_API_C( TQ3Status )
  344. Q3View_GetWorldToFrustumMatrixState (TQ3ViewObject         view,
  345.                                  TQ3Matrix4x4 *            matrix);
  346.  
  347. EXTERN_API_C( TQ3Status )
  348. Q3View_GetFrustumToWindowMatrixState (TQ3ViewObject     view,
  349.                                  TQ3Matrix4x4 *            matrix);
  350.  
  351.  
  352. /******************************************************************************
  353.  **                                                                             **
  354.  **                            Style state routines                             **
  355.  **                                                                             **
  356.  *****************************************************************************/
  357. EXTERN_API_C( TQ3Status )
  358. Q3View_GetBackfacingStyleState    (TQ3ViewObject             view,
  359.                                  TQ3BackfacingStyle *    backfacingStyle);
  360.  
  361. EXTERN_API_C( TQ3Status )
  362. Q3View_GetInterpolationStyleState (TQ3ViewObject         view,
  363.                                  TQ3InterpolationStyle * interpolationType);
  364.  
  365. EXTERN_API_C( TQ3Status )
  366. Q3View_GetFillStyleState        (TQ3ViewObject             view,
  367.                                  TQ3FillStyle *            fillStyle);
  368.  
  369. EXTERN_API_C( TQ3Status )
  370. Q3View_GetHighlightStyleState    (TQ3ViewObject             view,
  371.                                  TQ3AttributeSet *        highlightStyle);
  372.  
  373. EXTERN_API_C( TQ3Status )
  374. Q3View_GetSubdivisionStyleState    (TQ3ViewObject             view,
  375.                                  TQ3SubdivisionStyleData * subdivisionStyle);
  376.  
  377. EXTERN_API_C( TQ3Status )
  378. Q3View_GetOrientationStyleState    (TQ3ViewObject             view,
  379.                                  TQ3OrientationStyle *    fontFacingDirectionStyle);
  380.  
  381. EXTERN_API_C( TQ3Status )
  382. Q3View_GetReceiveShadowsStyleState (TQ3ViewObject         view,
  383.                                  TQ3Boolean *            receives);
  384.  
  385. EXTERN_API_C( TQ3Status )
  386. Q3View_GetPickIDStyleState        (TQ3ViewObject             view,
  387.                                  unsigned long *        pickIDStyle);
  388.  
  389. EXTERN_API_C( TQ3Status )
  390. Q3View_GetPickPartsStyleState    (TQ3ViewObject             view,
  391.                                  TQ3PickParts *            pickPartsStyle);
  392.  
  393. EXTERN_API_C( TQ3Status )
  394. Q3View_GetAntiAliasStyleState    (TQ3ViewObject             view,
  395.                                  TQ3AntiAliasStyleData * antiAliasData);
  396.  
  397.  
  398. /******************************************************************************
  399.  **                                                                             **
  400.  **                        Attribute state routines                             **
  401.  **                                                                             **
  402.  *****************************************************************************/
  403. EXTERN_API_C( TQ3Status )
  404. Q3View_GetDefaultAttributeSet    (TQ3ViewObject             view,
  405.                                  TQ3AttributeSet *        attributeSet);
  406.  
  407. EXTERN_API_C( TQ3Status )
  408. Q3View_SetDefaultAttributeSet    (TQ3ViewObject             view,
  409.                                  TQ3AttributeSet         attributeSet);
  410.  
  411.  
  412. EXTERN_API_C( TQ3Status )
  413. Q3View_GetAttributeSetState        (TQ3ViewObject             view,
  414.                                  TQ3AttributeSet *        attributeSet);
  415.  
  416. EXTERN_API_C( TQ3Status )
  417. Q3View_GetAttributeState        (TQ3ViewObject             view,
  418.                                  TQ3AttributeType         attributeType,
  419.                                  void *                    data);
  420.  
  421.  
  422.  
  423.  
  424. #if PRAGMA_ENUM_ALWAYSINT
  425.     #pragma enumsalwaysint reset
  426. #elif PRAGMA_ENUM_OPTIONS
  427.     #pragma option enum=reset
  428. #elif defined(PRAGMA_ENUM_PACK__QD3DVIEW__)
  429.     #pragma options(pack_enums)
  430. #endif
  431.  
  432. #if PRAGMA_STRUCT_ALIGN
  433.     #pragma options align=reset
  434. #elif PRAGMA_STRUCT_PACKPUSH
  435.     #pragma pack(pop)
  436. #elif PRAGMA_STRUCT_PACK
  437.     #pragma pack()
  438. #endif
  439.  
  440. #ifdef PRAGMA_IMPORT_OFF
  441. #pragma import off
  442. #elif PRAGMA_IMPORT
  443. #pragma import reset
  444. #endif
  445.  
  446. #ifdef __cplusplus
  447. }
  448. #endif
  449.  
  450. #endif /* __QD3DVIEW__ */
  451.  
  452.